Copyright: Copyright 1996, 1997 Symantec Corporation
Citation: Reprint permission by Symantec Corporation, Visual Cafe Pro 1997


 Pro extension online help project

This help project only contains the "Pro" element of Visual Cafe Pro:

•	Context sensitive help: Context sensitive help is done by including the engineer's helpid.txt file into the help compile. The mapping between the engineer's ID and the Topic ID is done in an included Alias file called alias.txt.

•	Styles: The project's .doc files are based on (attached to) robohelp.dot (for vcafepro.doc) and robortf.dot (for all other .doc files). The style definitions are in prohelp.dot. To change a style definition, change it in prohelp.dot. To update a .doc with the latest style definitions, merge in prohelp.dot. To merge in prohelp.dot, choose Format | Style Gallery and select prohelp.dot.

•	Heading 1: I applied prohelp.dot with the new heading 1 definition only to f1_pro.doc, not to the other .doc files because its wasn't necessary.

•	Windows: This project uses three windows: overview, how_to, and substeps.

--------------------------------------------------------------------------------------------------------------------------

A complete Visual Cafe Pro help collection is the following pieces:

•	vcafe.hlp

•	customized vcafe.cnt

•	the old vcafe.cnt (renamed cafebase.cnt)

•	vcafepro.hlp

•	dbaw.hlp

•	and any other .hlp project that were used in Visual Cafe, such as macro.hlp apiref.hlp, concepts.hlp, compnts.hlp

There should be no need for a compile to create a Pro release, just a compile of the Pro extension project vcafepro.hlp.

Step 1: Copy all of the Visual Cafe .hlp and .cnt files to a empty directory.

Step 2: Rename vcafe.cnt to vcafebase.cnt.

Step 3. Create a custom .cnt for Pro that "includes" the .hlp's .cnt files. Start by copying the previous custom vcafe.cnt (as backup is called vcafemaster.cnt.). To get the right "look", you may have to also customize vcafebase.cnt to move topics that are listed there into the vcafe.cnt so that the outline looks correct.

:Base vcafe.hlp>visual

:Title Visual Cafe Pro Help

:Index dbANYWHERE help =dbaw.hlp

:Index Pro extension help =vcafepro.hlp

:Index Visual Cafe Help =Vcafe.hlp

:Link Vcafe.hlp

:Link Vcguide.hlp

:Include vcafebase.cnt

:Include vcafepro.CNT

:Include dbaw.cnt

1 Components Reference

2 Components Summary=Visual_Cafe_components_and_containers

2 Properties Summary=Properties_summary

2 Event Summary=Events_Overview

2 Alphabetic listings

3 Components

4 Standard and dbAWARE components

...

4 dbAWARE only components

...

4 Standard components

...

3 Properties

4 dbAWARE properties

...

4 General properties

...

3 Events

...

1 Glossary

2 Glossary=Glossary

Step 4: Make a copy of the final vcafe.cnt and call it vcafemaster.cnt.

Step 5: Prefold ALL of the .hlp and .cnt files. You will have to contact the build engineer for the correct build directory(s) and the current prefold script.

----------------------------------------------------------------------------------------------------------------------------

The vcafepro.hlp project

Do not add topics to this file, vcafepro.doc. This is the base .doc file for help and is used for project information only.

This project consists of these files:

F1_pro.doc	F1 help topic – menus, dialogs, window, etc
gloss.doc	Glossary of terms (added 3/10/97)
ctaskpro.doc	Component related How To tasks for dbAware components. Document other component howtos in vcafe.hlp ctask.do
taskspro.doc	Pro procedures and task; taken from F1_Pro and new.
Trblpro.doc	Troubleshooting topics for Pro
errorpro.doc	Pro error messages

You need this file from the engineers:

helpidpr.txt	A file provided by the engineers. Simply update the file exactly as you get it from the engineers (Note you have to rename  their  file to the name helpidpr.txt). Contains the hex number that the software calls and the help ID that the software thinks that is should look for. Since our topic IDs don't match, that is why we have the alias.txt file.
You create this alias file:

aliaspro.txt	Context sensitive help is done by including the engineer's helpid.txt file into the help compile. This file maps engineering help ID strings to help topic IDs for context-sensitive help
Notes:

•	To enable cross .hlp file linking, you must list the files in the Content Tab Composer>>Contents>>Setup...>> Link Files option. The Alinks of other .hlp files don't show up in the A word listing. You have to know the A word and type it in manually.

•	WARNING: For this project the Topic ID and A Search Word fields in the Topic definition must be EXACTLY the same and only use ONE A Search Word.

•	The mapping between the engineer's ID and the Topic ID is done in an included Alias file called alias.txt.

•	since this is a multiple writer project. Everyone should use shared templates robohelp.doc and robortf.dot


f1_pro.doc

•	Contents: This file contains the F1 context-sensitive help for Visual Cafe Pro.

•	Dialog box topics: A wizard page topic can be accessed only from a wizard page or a Details button in a procedure topic (not from the index, no keywords) – because a wizard page topic doesn't make sense unless you are looking at the wizard page.

History

1/16/97: Added topics for dbNAVIGATOR items to testing

2/12/97: Removed procedures and made them their own file.

3/10/97 -- Engineering review


Windows


Understanding dbNAVIGATOR

Window [image] dbNAVIGATOR

dbNAVIGATOR lets you access dbANYWHERE Servers, and the databases that are managed by the servers. When you connect to a dbANYWHERE Server, dbNAVIGATOR displays a list of servers and Data Sources that are currently connected.

You can add dbAWARE component to a form by dragging a database table or column to the Form Designer.

dbNAVIGATOR contains a hierarchy with the following items:

Item	Description
dbANYWHERE Server items	Represents a dbANYWHERE Server that can be accessed by the computer that Visual Cafe Pro is running on.
Data Source items	Represents a database that is connected to the associated dbANYWHERE Server.
Database Table items	Represents a table in the associated database. When you connect to a database, dbNAVIGATOR displays the tables and columns that are in the database.
Database Column items	Represents a column in the associated database table.
Tasks

Adding a table to your project

Connecting to a dbANYWHERE Server

Connecting to a database

Disconnecting a database

Refreshing dbNAVIGATOR


Server item

A dbANYWHERE Server item represents a dbANYWHERE Server that can be accessed by the computer Visual Cafe Pro is running on.


Data Source item

A Data Source item represents a database that is connected to the associated dbANYWHERE Server. When you connect to a dbANYWHERE Server, dbNAVIGATOR displays data source items for the databases that are connected to the dbANYWHERE Server.


Table item

A Database Table item represents a table in the previous database. When you connect to a database, dbNAVIGATOR displays the tables and columns that are in the database.


Column item

A Database Column item represents a column in the previous database table. When you connect to a database, dbNAVIGATOR displays the tables and columns that are in the database.


Pop-up menus


dbNAVIGATOR pop-up menu

When you right-click in dbNAVIGATOR, Visual Cafe Pro displays a pop-up menu with the following commands:

Insert Server

Opens the dbANYWHERE Server dialog box that lets you connect to a dbANYWHERE Server. This command is available only if a dbANYWHERE Server is selected.

Connect

Opens the Logon dialog box that lets you logon to a data source. This command is available only if a Data Source is selected.

Disconnect

Disconnects the selected database.

Refresh

Refreshes the selected database's dbNAVIGATOR tables and columns information . This command is useful for multiple concurrent users. This command is available only if a Server or Data Source is selected.


Wizards


Using Visual Cafe Pro wizards

Visual Cafe Pro provides wizards that help you:

•	create a project

•	create a database table based on a template

•	add a table to your project

The wizard allows you to choose database tables, variables in the tables, and the action that is to be performed. The applet, or application, is then constructed and displays in the Form Designer.

When using a wizard, you are asked to make the following choices:

1.	The dbANYWHERE Server, database, table, and columns to access.

2.	The components and labels to display on the form.

3.	The database actions to provide on the form. The form displays a button for each action.


Dialog boxes


Using the dbANYWHERE Server dialog box

dbNAVIGATOR [image] Insert Server popup menu option

The dbANYWHERE Server dialog box lets you select the type of project, a dbANYWHERE Server that is already connected, or make a new dbANYWHERE Server connection.

To select a dbANYWHERE Server that is already connected

Choose a name from the dbANYWHERE Server Name list. The dialog box fills in the Host Name or IP Address and the Port Number for you.

To make a new dbANYWHERE Server connection

1.	Enter a name for the dbANYWHERE Server item. Visual Cafe Pro maked sure that the name follows the standards for Java™ class names. For example, if the name you enter includes spaces ("My dbANYWHERE Server"), Visual Cafe Pro replaces the spaces with underscores ("My_dbANYWHERE_Server").

2.	Enter the dbANYWHERE Server’s host name or IP address

3.	Enter the dbANYWHERE Server’s port number .

Troubleshooting

I can’t connect to a server

•	Do you have the right IP address and port number?

•	do you have access to the IP address?

•	Is the target machine available? (try a "ping" utility)

•	Is dbANYWHERE running on the target machine?

•	Do you have the proper version of the dbANYWHERE class file?

See Also

Connecting to a dbANYWHERE Server machine

Creating a Data Source configuration file

Checking dbANYWHERE connections

Setting up a dbANYWHERE system

Using the Data Source Tool

Using the dbANYWHERE Admin tool

Using the dbANYWHERE Service Manager


Wizard pages


Using the Start wizard page

The Start wizard page describes the wizard's main steps.


Using the Project Type wizard page

The Project Type wizard page lets you choose the type of project to create.

Option	Description
Applet	A program that can be added to a Web page and run by Java-enabled Web browsers (or the AppletViewer).
Application	An extension of Frame, the class created from the Application template is a good base class for a main application window. It can exist by itself, contain components and menus, and can be used to show dialogs and windows.


Using the Template wizard page

The Template wizard page lets you choose a template for your database table.

Visual Cafe Pro provides the template set.


Using the Database wizard page

The Database wizard page lets you select a database.

1.	Choose a name from the database list. The list displays the databases that are connected to the dbANYWHERE Server you selected previously.

2.	If you haven't connected to the database yet, the Database wizard page displays the Logon dialog box that lets you logon to the database.

   Details on this step


Using the Logon dialog box

The Logon dialog box lets you logon to a database.

1.	Enter a user name.

2.	Enter a password.

3.	Select or clear the check box. If you select the check box, dbNAVIGATOR displays only the database tables owned by the specified user name.

Troubleshooting

I can't get logged on the database


Using the Database Table wizard page

Insert [image] Add Table Wizard

The Database Table wizard page lets you select a database table from the previously specified server.

Choose a name from the list.


Using the Database Columns wizard page

The Database Columns wizard page lets you choose the database columns that you want to access. The list displays columns in the previously specified database.

To deselect a column, click its check box.


Using the Components and Labels wizard page

The Components and Labels wizard page lets you select a component and specify a label for each database column. At runtime, the applet or application displays each column's data in its component and displays a label for the component. The wizard page displays a default component and label for each column.

To change a column's component

1.	Click on the component name.

2.	Choose a component from the list that appears.

To change a column's label

1.	Click on the text for the label.

2.	Enter new text. Visual Cafe Pro will make sure that the text follows the standards for Java™ labels. For example, if the text you enter includes spaces ("Employee first name"), Visual Cafe Pro will replace the spaces with underscores ("Employee_first_name").

Note  If you don't want the component to have a label, click on the text for the label and delete it.

Tip  You can change the component’s label after it is built by modifying the component’s Text property.


Using the Actions wizard page

The Actions wizard page lets you select the actions that the  applet or application provides. At runtime, the form displays a button for each action.

To select database operations

Click the check box for each action you want enabled on the form via buttons.

To change a button's text

1.	Click on the text.

2.	Enter text for the button. Visual Cafe Pro makes sure that the text follows the standards for Java labels. For example, if the text you enter includes spaces ("Employee first name"), Visual Cafe Pro replaced the spaces with underscores ("Employee_first_name").

Tip  To change properties of an action button after being generated by the wizard, you can use the Property List.

Tip  To create an action button outside of the wizard, add a button component to the form. With the button component selected, choose the Add Interaction option from the right-mouse popup menu. Use the Interaction Wizard to specify the appropriate action for the button.


Using the Master View wizard page

The Master View wizard page lets you select a table for a master view in a master/detail relationship.

The table you choose in this wizard page is the master view and the table you are creating is the detail view.

The list box displays the tables that represent RelationViews that exist in your project.

Note  If you don't want to create a master/detail relationship, choose "None."


Using the Join Definition dialog box

Property List [image] Join property

The Join Definition dialog box lets you create or change a detail view's join that defines a master/detail relationship. A master/detail join is useful when you have tow or more tables that have a one-to-many relationship, such as a customer order that has multiple order items.

Note  The Join Definition dialog overrides the SQL statement created for the detail RelationView, depending on the Join criteria that is specified.

1.	Choose a column from the master view by clicking a cell under "Master Column" and choosing a column from the list.

2.	Choose a column from the detail view by clicking a cell under "Detail Column" and choosing a column from the list.

3.	Choose an operator for the relationship between the two columns by clicking a cell under "Operator" and choosing an operator from the list.


Using the Finish wizard page

The Finish wizard page displays the choices you made during the wizard.

To change a selection, go back to the wizard page where you made that selection by using the Back button.


Using the SQL Statement dialog box

Property List [image] Select Statement property

The SQL Statement dialog box lets you change a single RelationView's Select Statement property. The Select Statement property is a SQL statement.

Note  The Join Definition dialog overrides the SQL statement created for the detail RelationView, depending on the Join criteria that is specified.

The SQL statement dialog box has the following sections:

Section	Description
Edit box	The SQL statement you are editing.
Functions	Functions you can add to the SQL statement. The functions in this list are the functions the database supports.
Columns	Database columns that are in the current RelationView. You can add any of these columns to the SQL statement.
Keywords	Keywords you can add to the SQL statement. The keywords in this list are the keywords the database supports.
Operators	Numbers and mathematical operations you can add to the SQL statement.


taskspro.doc

•	Contents: This file contains the procedure topics for Visual Cafe Pro, and some overview topics

•	Dialog box topics: A dialog box topic can be accessed only from a dialog box or a Details button in a procedure topic (not from the index, no keywords) – because a dialog box topic doesn't make sense unless you are looking at the dialog box.

History

2/12/97: Created and added to project


Intro


Welcome to Visual Cafe Pro

Symantec's Visual Cafe Pro for Windows is the first complete Rapid Application Development (RAD) environment for Java that  provides full database connectivity. Featuring a sophisticated set of high level tools, Visual Cafe Pro is the hottest Java database development environment available today.

The environment

Visual Cafe Pro takes Java development to a new level by incorporating three powerful development tools:

•	Visual Cafe

•	the Pro Extension

•	dbANYWHERE Workgroup Server

You can assemble complete Java applets and applications from a library of standard and third party objects without writing source code. Visual Cafe Pro seamlessly integrates visual and source development of Java software, letting you switch effortlessly between visual and source views. Modifications that you make in the visual view are immediately reflected in the source code. The source code automatically updates changes to the visual view.

This help system

The Visual Cafe Pro help system is composed of the Visual Cafe online help (vcafe.hlp), Visual Cafe user concepts (vcguide.hlp), help on the Pro extensions (vcafepro.hlp), and the dbANYWHERE online help (dbaw.hlp).


Pro Extension Overview

Visual Cafe Pro extends the Visual Cafe development environment and generates code to the dbANYWHERE Workgroup Server's Pro Extension.

The Pro Extension binds components with the dbANYWHERE Server. When data changes in the dbANYWHERE server, or the current row changes, the Pro Extension automatically updates and informs dbAWARE components. In this way, the Pro Extension provides functionality for typical database operations.

The three main modules in the Pro Extension are the

•	database wizards

•	dbNAVIGATOR

•	dbAWARE components

The Visual Cafe Pro wizards step you through complicated processes, such as

•	creating a new form over a data source table

•	adding data source table connectivity to an existing form

•	defining master/detail joins

•	creating tables and form from predefined templates

The wizards develop the applications using the Pro Extension and the dbANYWHERE API.

dbNAVIGATOR provides a hierarchical view of data source cataloging information known as meta-data. This view lets you see dbANYWHERE servers, available data sources, as well as the tables and columns in each data source.

dbAWARE components encompass and simplify database connectivity and facilitate binding to database columns. dbAWARE Java forms communicate with data sources through the dbANYWHERE server.


Visual Cafe Pro versus dbANYWHERE tasks

Visual Cafe Pro provides the user interface to design forms that interact with a data source. The software element that defines and manages the data source connectivity is dbANYWHERE.

Many connectivity tasks are documented in the dbANYWHERE online help.

You can access the dbANYWHERE information from the

•	Visual Cafe Pro online help Contents list

•	Visual Cafe Pro Help menu, dbANYWHERE topic...

•	dbANYWHERE Help menu

Some common tasks that are controlled by dbANYWHERE are

•	connecting to a data source

•	retrieving data from a data source

•	updating a data source

dbANYWHERE topics

Connecting to a dbANYWHERE Server machine

Creating a Data Source configuration file

Checking dbANYWHERE connections

Setting up a dbANYWHERE system

Using the Data Source Tool

Using the dbANYWHERE Admin tool

Using the dbANYWHERE Service Manager


Using the dbANYWHERE API

Visual Cafe Pro is composed of Visual Cafe, special data source connectivity components and wizards, and dbANYWHERE Workgroup Server. When using the wizards and components, Visual Cafe Pro automatically generates Java code that includes calls to the dbANYWHERE API.

The dbANYWHERE Workgroup Server has its own API.

The dbANYWHERE API

•	adheres to the JDBC standard created by Sun Microsystems

•	supports simultaneous access to multiple databases both local and remote

•	provides simple database functionality in powerful, easy-to use classes.

•	supports the three-tier system architecture, where the first tier is the client program, the second tier is the dbANYWHERE middleware and database drivers, and the third tier consists of the database servers.

Use the dbANYWHERE API  to

•	manage transactions, database connections, data buffering, heterogeneous joins and all other database communications.

•	simultaneously access multiple databases

•	manage database handle sharing capabilities (This lets you significantly reduce the number of database licenses.)


Procedures, in alphabetic order


Adding a table to your project

The Add Table wizard helps you add a table to your project. If your project already has a RelationView, you can create a master/detail relationship.

Start the Add Table wizard by choosing Insert [image] Add Table Wizard.


Changing a view

A RelationView component represents a view. A RelationView's SQL statement (Select Clause property) defines the view. A view may or may not be a detail view.

To change a view

1.	Choose Window [image] Property List.

2.	Choose a RelationView from the Property List's drop-down menu.

3.	Select the value for the Select Clause property.

4.	Click the [image] button to open the SQL Statement dialog box.

5.	Use the dialog box to change the SQL statement.

   Details on this step


Changing a master/detail relationship
Creating a master/detail relationship

A master/detail relationship is the relationship between a detail view and its master view. A RelationView's join (Join properties) defines the relationship.

1. 	In the Form Designer, click on the RelationView component that will represent the detail view.

2.	Click in the Join Columns property field.

3.	Click the [image] button to open the Join Definition dialog box.

4.	Use the dialog box to change the join definition.

   Details on this step


Creating a MultiView

The RelationView class can encapsulate a MultiView object. For example, RelationView.saveMultiView( ) translates to MultiView.save( ) for the RelationView's parent MultiView.  MultiView  is a container class for the dbANYWHERE database transaction object. A MultiView contains a transaction's RelationViews.

To interact with a dbANYWHERE Server, you do not have to interface directly with a MultiView object. However, a  MultiView object can be useful to global transactions that have a handle to a MultiView object.

For detail information on the MultiView class, see the dbANYWHERE API online manual (Help [image] Database API Reference)


Connecting to a dbANYWHERE Server

In order to access a data source, you must first connect to a dbANYWHERE Server that has the data source registration.

1.	Choose Window [image] dbNAVIGATOR.

Note: If you display dbNAVIGATOR and it is empty, Visual Cafe Pro opens the dbANYWHERE Server dialog box.

2.	Right-click to display dbNAVIGATOR's pop-up menu.

3.	Choose Insert Server to open the dbANYWHERE Server dialog box.

4.	Use the dialog box to connect to a dbANYWHERE Server.

   Details on this step


Connecting to a database
Connecting to a data source

Once you have established a dbANYWHERE connection, you can select a data source form the list of available data sources.

1.	Choose Window [image] dbNAVIGATOR.

Note  If you display dbNAVIGATOR and it is empty, Visual Cafe Pro opens the dbANYWHERE Server dialog box.

2.	Choose a data source by clicking on a DataSource item. Visual Cafe Pro opens the Logon dialog box.

Note  If you don't see the data source you want, then you haven't connected to the correct dbANYWHERE Server.

3.	Provide a username and password for the data source when prompted.

   Details on this step

Note  You can connect to the data source at any time. When developing a Java applet that uses a database, Visual Cafe pro maintains one persistent connection. A separate connection is made automatically when running the applet, which is disconnected once the applet is terminated.


Creating a dbAWARE project

The Project wizard helps you create a project for an applet or application.

To start the Project wizard

1.	Choose File [image] New Project.

2.	Choose the dbAWARE Project Wizard.


Creating a database table based on a template
Creating a data source table based on a template

The dbAWARE Template wizard helps you create a data source table based on a Visual Cafe Pro template.

To start the dbAWARE Template wizard

1.	Choose File [image] New Project.

2.	Choose the dbAWARE Template Wizard.


Creating a view

A RelationView component represents a view. A RelationView's SQL statement (Select Clause property) defines the view. You can create a view that is a detail view or a view that is not a detail view. Before creating a detail view, your project needs to have a RelationView to use as the master view. When you create a detail view, you are also creating a master/detail relationship. To create a view that is not a detail view, you can use the Project wizard or the Add Table wizard.

To create a view that is not a detail view by using the Project wizard

Use the Project wizard to create a new project.

   Details on this step

To create a view that is not a detail view by using the Add Table wizard

Use the Add Table wizard to add a table to your project. The new table represents the new view.

   Details on this step

To create a detail view

Use the Add Table wizard to add a table to your project. The new table represents the new view.

   Details on this step


Customizing Visual Cafe Pro code

To extend the capabilities and behavior of your Visual Cafe Pro project, you may want to customize the code generated by Visual Cafe Pro.

When working in a Visual Cafe Pro project, you may see the following code segments:

// Take out this line if you don't use symantec.itools.net.RelativeURL
symantec.itools.lang.Context.setDocumentBase(getDocumentBase());

Also see Adding Code to a Java source file.


Deleting a view

To delete a view, simply delete the RelationView component.


Disconnecting a database
Disconnecting a data source

To disconnect from a data source

1.	Choose Window [image] dbNAVIGATOR.

2.	Choose a data source by clicking on a DataSource item.

3.	Right-click to display dbNAVIGATOR's pop-up menu.

4.	Choose Disconnect.


Refreshing dbNAVIGATOR

Refreshing dbNAVIGATOR updates dbNAVIGATOR's display for a data source's tables and columns. Refreshing dbNAVIGATOR is useful for multiple concurrent users.

1.	Choose Window [image] dbNAVIGATOR.

2.	Choose a data source by clicking on a DataSource item.

3.	Right-click to display dbNAVIGATOR's pop-up menu.

4.	Choose Refresh.


This file contains the error message topic

2/12/97: Created and added to project, new for release 1.0d


Visual Cafe Pro error messages

symantec.itools.db.net.NetException: Server not responding

What does this mean?	What do I do about it?
The Java client was not able to establish a connection with the specified dbANYWHERE server.	Make sure dbANYWHERE is running normally at the location specified in the connection URL.  If the server is remote, make sure there is a good network connection to it.
Client/server mismatch

What does this mean?	What do I do about it?
dbANYWHERE Server comes with DBAW.ZIP, SQL.ZIP, and DBAW_AWT.ZIP, which replaces the SYMANTEC.ZIP that ships with the Workgroup Server version.	You need to use these instead of the SYMANTEC.ZIP.   Update the SC.INI file.  Remove the entry for SYMANTEC.ZIP and reference the new ZIP files that are included with dbANYWHERE Server.


Pro Troubleshooting

Various topics

3/10/97- new document for release 1.0d


Why are applets disconnecting from the database at runtime?

Problem statement

When running an applet in a browser, resizing the browser causes the database connection to be lost.

Solution

One major issue facing Java applets running in typical Internet browsers is browser resizing. Default logic seems to be the destroying and restarting of a Java applet upon any change to the size of the browser window.

If session.close() is called when destroying the applet, the data connection is lost and must be re-established when the applet is restarted.

The solution provided by default in Visual Cafe Pro is to maintain a persistent database connection. This means that any browser resizing will not lose the connection. However, the disadvantage is that the connection will be maintained until the browser is closed. As a possible solution, you may want to provide a Close button on the applet that calls session.close().


I can't connect to a server

Problem statement

While in dbNAVIGATOR or on the dbANYWHERE Server dialog box, I get an error message about the server not being available.

Solution

See

Troubleshooting a dbANYWHERE connection

Troubleshooting a Data Source conenction


I can't get logged on to the database

Problem statement

I complete the logon dialog box but I can’t get logged on.

Solution

Check your password and user name.

You server may not be connected. Be sure that you have followed the procedure for connecting a server.

See

Troubleshooting a dbANYWHERE connection

Troubleshooting a Data Source conenction


When I view my project in a browser layered components seem to be missing
When I view my project in a browser layered components seem to be missing.

Problem statement

You added components to your project that sit on top or underneath another component. The components are listed as project objects and you can see them a design time, but they do not work or you can’t see them at runtime.

Solution

Browser behavior is not consistent across platforms; and browsers display Java applets and applications differently. One common problem is the display of components that are layered. Some browsers use the order in which the component objects are listed in the Project window to determine layer order, others don’t.

This is often a problem when using InvisibleButtons on top of an image. The workaround for this browser problem is to have a duplicate InvisibleButton under the image. So, if the user’s browser “flips” the component layering, the element maintains its intended behavior.


TBD

Problem statement

State problem

Solution

Need info


Definitions


A


access type

Scope of a variable or method:

•	Public: Accessible from any class.

•	Protected: Accessible from the class that defines the variable or method and from the class' subclasses.

•	Private: Accessible from the class that defines the variable or method.

•	Package: Accessible from any class in the package that defines the variable or method. This is the default access type.


action

Action performed on a database:

•	delete: Deletes the current record from the Data Source.

•	first: Moves the database cursor to the first record in the database table.

•	new: Creates a new record in the database table.

•	next: Moves the database cursor to the next record in the database table.

•	prev: Moves the database cursor to the previous record in the database table.


active window

Window which receives keyboard input. Only one window can be active at any time.


anchor component

Component which acts as the reference point when modifying a group of components. When you select multiple components, the last component selected is the anchor component. It has distinct, colored selection handles.


applet

Program

Special type of Java program that you can add to a Web page. To run an applet:

•	Add the applet to a Web page and display the Web page in a Java-enabled Web browser.

-or-

•	Run the applet from the Applet Viewer. (The Applet Viewer is a tool that Sun provides with the JDK. The Applet Viewer is also included in Visual Cafe and Visual Cafe Pro.)

Class

Class in the Java API.


application

Program

Java program you can run from a computer that has the Java Virtual Machine.

Template

Template provided by Visual Cafe (and Visual Cafe Pro) when you choose File [image] New Project [image] Basic Application. This template creates a class that is an extension of the Frame class. This class is a good base for a main application window.


B


boolean expression

Expression that evaluates to true or false.


Breakpoints window

Window that contains a list of all breakpoints in a project. Use this window to add, remove, or modify breakpoints. To see the Breakpoints window:

Window [image] Breakpoints


bytecode

Machine-independent code generated by the Java compiler and executed by the Java interpreter.


C


Call Stack window

Window that, at runtime, shows all the active method calls leading to the current process. When an applet or application calls a method, the Java Virtual Machine (Java VM) adds the method to the stack. When the method returns, the Java VM takes it off the stack. The currently executing method is on the top of the stack and the previous methods called are below it. To see the Call Stack window:

Window [image] Call Stack


class

Collection of variables and methods that you can use to define an object. The variables define the class' structure. The methods define the class' behaviors.


Class Browser

Window that consists of:

•	Classes pane: Hierarchy of all classes.

•	Members pane: Hierarchy of a project's methods and data.

•	Source pane: Project's source code. You can edit the source code in this pane.

To see the Class Browser:

Window [image] Class Browser


client machine

Machine that communicates with a dbANYWHERE Server machine to access a Data Source.


client software

Software that dbANYWHERE uses to communicate with a database engine such as:

•	Oracle Server client software

•	Microsoft SQL Server client software

•	ODBC32 Administrator


component

Object that your applet or application defines or uses to create a visual interface.

•	A component is a class with a set or properties, a visual element, a collection of event methods and associated code, and, optionally, an interaction.

•	A component is visual or hidden. A visual component is visible at runtime and lets users interact with your applet or application. A hidden component is not visible at runtime.

•	A component may contain other components. For example, forms and applets may contain other components.

•	Use the Component Palette or the Component Library to add components to your applet or application.

•	During development, you can use the Property List to customize a component's properties. You can also change a component's events to change its runtime appearance and behavior.

•	Components are called “controls” in C++.


Component Library

Collection of components that you can add to your applet or application. When you create a project template or add a component to the Component Palette, Visual Cafe adds the component to the Component Library. To see the Component Library:

Window [image] Component Library


Component Palette

Palette that provides easy access to components. You can place any component in the Component Library on the Component Palette.


conditional breakpoint

Breakpoint that lets you stop program execution when a specified expression evaluates to true.


connection statistics

DC messages which occur when a client disconnects. The format for a DC message is:

DC, <client IP address>, <initial connect time>, <connect time duration>, <number of requests processed>

where:

•	<initial connect time> is in second since 1970

•	<connect time duration> is in seconds


container

Component that can contain other components. For example, Form and Panel are containers.


context menu

Menu that appears when you click the secondary mouse button in a Visual Cafe window. A context menu is often called a pop-up menu.


D


database template

Empty database table with pre-defined columns. Each Visual Cafe Pro database template is designed for a specific type of information.


Data Source

Source of data. A Data Source is usually a database, but can be something else such as a spreadsheet. Sometimes a Data Source is called a DSN (Data Source Name). For information about the Data Sources that dbANYWHERE supports, see the "Installing dbANYWHERE Server" manual.


dbANYWHERE (naming conventions)

dbANYWHERE Server	Middleware database software that supports three-tier architecture for database access
dbANYWHERE Workgroup Server	Restricted version of the dbANYWHERE Server which is shipped with Visual Cafe Pro
dbANYWHERE Server machine	Hardware on which dbANYWHERE software is running
dbANYWHERE	Both versions of dbANYWHERE


dbAWARE component

Visual Cafe component that has additional properties for binding to a database.


dbNAVIGATOR

Window that lets you access dbANYWHERE Servers and the Data Sources that are connected to those servers. To see dbNAVIGATOR:

Window [image] dbNAVIGATOR


debug mode

Temporary suspension of a running program. In debug mode, you can edit code, edit forms, set or clear breakpoints, debug threads, and view the calls on the call stack. After making any edits, restart program execution to see the affect of the changes.


Debug toolbar

Toolbar that has buttons for debugging.


Debugging window

Window for debugging an applet or application. The Debugging window is a special mode of the Source window: It is the Source window while you are debugging.


declaration

Statement that establishes an identifier and associates attributes with it, without necessarily reserving its storage for data or providing the implementation for methods.


definition

Declaration that reserves storage for data or provides implementation for methods.


design time

Time during which you build an applet or application in the development environment.


development machine

Machine that combines a client machine and a Java development environment such as Visual Cafe Pro.


dialog bo

Window with a title bar that can receive and process input from a user.

•	Applets cannot use dialog boxes.

•	Dialog boxes are not suitable for an application's main window.

•	Dialog boxes can contain components, but not menus.

•	Use dialog boxes for temporary windows.


E


event

Action or occurrence to which an object can respond. Events are typically user actions that the program can capture and respond to. For example, mouse clicks, key presses, and mouse movements are events.


F


foreign key

Column or columns in one database table whose values match the primary key in another table. Foreign key columns may or may not be defined as Unique or NOT NULL.


form

Container for components that the user can work with at runtime. A form can contain other forms and other types of components. For example, windows, dialog boxes, message boxes, and applets are forms.


Form Designer

Window that displays a form's components.


frame

Window which can contain components and menus.


G


garbage collection

Automatic detection and freeing of memory that is no longer in use. The Java runtime system performs garbage collection which means that you don't have to explicitly free objects and other data.


H


hidden component

Component that is visible at design time and invisible at runtime. For example, menu bars, RelationViews, and Sessions are hidden components. To toggle between displaying and hiding hidden components at design time:

Layout [image] Invisibles


Hierarchy Editor

Window that displays the class hierarchy for your applet or application. To see the Hierarchy Editor:

Window [image] Hierarchy Editor


I


identifier

Name of an item in a Java program.


inheritance

Concept wherein classes automatically contain the variables and methods defined in their superclasses.


instance

Data item based on a class. An instance of a class is usually called an object. For example, multiple instances of a Form class share the same code and are loaded with the same components with which the Form class was designed. At runtime, the individual properties of components on each instance can be set to different values.


interaction

Relationship between two or more components. The components may be on the same form or on different forms. An interaction consists of:

•	Two or more components (trigger component and action component)

•	Trigger event

•	Action

For example, you can connect a button (the trigger component) to a text box (the action component) so that when the user clicks on the button (the trigger event), the associated text box is enabled for user input (the action).


J


Java API: Java Application Program Interface

API provided by the JDK. For more information, see the Java Web page (java.sun.com).


Java file

File that contains components and Java source code.


Java VM: Java Virtual Machine

Virtual machine provided with the JDK (Java Development Kit). The machine contains:

•	Bytecode translator that converts a downloaded binary Java file into instructions that the client machine can execute.

•	Library routines that a Java applet calls.

For more information, see the Java Web page (java.sun.com).


JDK: Java Developer's Kit

Tools for developing Java applets and applications. The JDK is included in Visual Cafe and Visual Cafe Pro. It is also available on the Java Web page (java.sun.com).


JDBC

Standard for Data Source access from Java applets and applications. JDBC is an API developed by Sun Microsystems. For more information, see the JDBC Web page (splash.javasoft.com/jdbc).


join

Definition of a master/detail relationship. Only detail views have joins. The Join properties for a detail RelationView define a join.


K


L


Layout

Property for container objects like forms and panels. The Layout property automatically arranges components in a container so that they display well on different platforms, screens, and at different resolutions.


list binding

Data binding that lets you display data from multiple database columns. List binding is helpful for populating list boxes.


local variable

Data item defined within a block of code and accessible only by the code within the block. For example, a variable defined in a Java method is a local variable and can't be used outside the method.


M


macro

Sequence of keystrokes. The Source editor's macro facilities let you record, save, and edit macros.


master/detail relationship

Relationship between a master view and a detail view. The detail view's join defines the relationship.


member

Variable or method defined in a class.


method

Behavior that acts on an object. A method is defined in a class.

•	Class method: Method invoked using a class name.

•	Instance method: Method invoked using the name of an instance (object).


Messages window

Window that displays all Visual Cafe informational and error messages. For example, if Visual Cafe detects an error during parsing, the error message is displayed here. You can double-click on an error message to open the file in which the error was detected. To see the Messages window:

Window [image] Messages


modal

Window or dialog box behavior that requires you to take some action before the focus can switch to another window or dialog box.


modeless

Window or dialog box behavior that does not require you to take some action before the focus can switch to another window or dialog box.


N


O


object

Instance of a class.


Objects view

View of a project that displays only visible components. To toggle between displaying and hiding hidden components at design time:

Layout [image] Invisibles


optimistic concurrency

Locking technique that maximizes concurrency. The DBMS doesn't lock data that is being viewed. It locks only data that is being modified.


overloading

Using one identifier to refer to multiple items in the same scope. In Java, you can overload methods but not variables or operators.


overriding

Providing a different implementation of a method in a subclass of the class that originally defined the method. Overridden methods have the same name but take different parameters.


P


package

Group of classes and interfaces.


Packages view

View of a project that displays both visible and hidden components. To toggle between displaying and hiding hidden components at design time:

Layout [image] Invisibles


panel

Container that you can add to another container. A panel doesn't have a visible border. You can use a panel to group a window into logical regions.


ping: Packet INternet Groper

Network message that a computer transmits to check for the presence, connectedness, and responsiveness of another computer. The other computer responds by echoing the message back to the first computer.


primary key

Column or columns in a database table that uniquely identify a record. A value in a primary key column cannot be NULL and must be unique.


project

Set of components and code that comprise an applet or application.


Project template

Collection of components that you can use as the foundation for an applet or application. When you choose a template for a new project, the new project inherits all of the template's components. For example, you can create project templates for Web sites, single documents, database projects, and applets.


Project window

Window that displays a project's objects or packages depending on which tab you select.


projection binding

Data binding to one row in a database column.


property

Attribute of a component. Properties define component characteristics such as size, color, label, or the state of an object, such as enabled or disabled. The Property List displays the properties of a project's components. To see the Property List:

Window [image] Property List


Property List

Window that displays a component's properties. To see the Property List:

Window [image] Property List


Q


R


refresh

Update dbNAVIGATOR's display for a database's tables and columns.


regular expression syntax

Syntax that lets you perform regular expression matching. Regular expressions are wild card characters. The pattern you search for can be a text string or a regular expression.

Wild card characters

?	Any character.
*	Zero or more occurrences of any character.
@	Zero or more occurrences of the previous character or expression.
% or <	Beginning of a line.
$ or >	End of a line.
[...]	Any of the characters listed between [ and ]. You can use a hyphen (-) to specify a range of characters. For example, [abc] matches a, b, or c; [a-z] matches any lowercase letter; [A-Za-z] matches any upper or lowercase letter.
[~...]	Any character except those listed between [~ and ]. You can use a hyphen (-) to specify a range of characters. For example, [~A] matches any character but A; [~abc] matches any character except a, b, or c; [~A-Za-z] matches any non-alphabetic character.
\	Take the following character literally instead of using it as a wild card character. For example, you can use \* to search for an asterisk or \\ to search for a backslash character.
\t	Tab character.
\f	Formfeed character.


RelationView

Visual Cafe Pro component that represents a view.


run mode

Mode wherein your applet or application is running. In run mode:

•	You can interact with your program as a user.

•	Visual Cafe replaces the Project Menu with the Debug Menu.


runtime

Time when your applet or application is running. At runtime:

•	You can interact with your program as a user.

•	You can pause the application and start debugging by pressing CONTROL+BREAK.


S


scope

Access type of a variable or method:

•	Public: Accessible from any class.

•	Protected: Accessible from the class that defines the variable or method and from the class' subclasses.

•	Private: Accessible from the class that defines the variable or method.

•	Package: Accessible from any class in the package that defines the variable or method. This is the default access type.


server

•	Database server: Computer that stores and manages a database.

•	dbANYWHERE Server: Computer that runs dbANYWHERE which is middleware database software that supports three-tier architecture for database access.

•	File server: Computer that stores programs and data files.

•	Web server: Computer that stores and sends out Web pages in response to HTTP requests from Web browsers.


Source pane

Pane in the Source window and Class Browser that lets you view and edit code.


Source window

Window that display's a project's source code. You can edit the source code in this window. The Source window turns into the Debugging window when you are debugging. To see the Source window:

1.	Right-click in the Form Designer to display the context menu.

2.	Choose Edit Source.


SQL statement

SQL 92 string that defines a view. If the string is in the standard SELECT statement format as shown below, Visual Cafe Pro's wizards and Join Definition dialog box can parse the string and edit it for you. If the string is not in the standard SELECT statement format, you need to use the SQL Statement dialog box to edit the string manually.

Standard format

SELECT column[, column ...] FROM table WHERE condition

Example

SELECT emp_fname, emp_lname, location_id FROM emp_info WHERE location_id BETWEEN 10 AND 20


stored procedure

Collection of SQL statements that is named and pre-compiled.


T


thread

Path of execution in a running application. For example, an application can have threads that handle background processes that aren't visible to the user.


Threads window

Window that, at runtime, displays all the existing threads your program has created and the state of each thread. To see the Threads window:

Window [image] Threads


U


V


ValueTip

Interface element in Visual Cafe that displays the value of the variable that is under the cursor in the Source window in debug mode.


variable

Structure in memory which holds data that has been assigned to it. A variable that is defined in a class defines the class' structure.

•	Class variable: Variable associated with a class and not with a particular instance of the class.

•	Instance variable: Variable associated with an instance of a class (an object).


Variables window

Window that, at runtime, shows the variables that are active in the current context. To change a variable's value at runtime, edit its value in this window. To see the Variables window

Window [image] Variables


view

In a development environment

Window that shows a particular type of information.

•	Global view: View that is accessible from the Window menu. The global views are: Breakpoints window, Call Stack window, Class Browser, Component Library, Component Palette, Hierarchy Editor, Output window, Property List, Threads window, Variables window, Watch window.

•	Local view: View that is local to a project. The local views are: Project window, Source window.

For Data Sources

Virtual database table that exists only in memory. A RelationView represents a view. A RelationView's Select Clause property (which is a SQL statement) defines the view.

•	Master view: View that is used as the basis for a detail view.

•	Detail view: View that is related to a master view. A detail view's join defines a master/detail relationship.

•	A view can be a master view or a detail view or both or neither.


Visual Cafe window

Main development environment window that contains the menu bar and toolbars.


W


Watch window

Window that, at runtime, displays the value of a variable or expression you enter. You can modify these values directly in this window. To see the Watch window:

Window [image] Watch


window

Area that has no borders and no menu bar.


workspace

Saved window arrangement. Your workspace is saved automatically while you work.


X


Y


Z


URLs (not pop-ups)


dbANYWHERE Server machine URL

Address of a dbANYWHERE Server machine on the Internet. The format is:

dbaw://IPaddress:Port

Tip

To determine a dbANYWHERE Server machine’s IP address and port number when running in console mode, look at the dbANYWHERE title bar. To determine a dbANYWHERE Server machine's IP address and port number when running in Service mode, look at the dbANYWHERE startup messages.

Usage

Your clients need to use this IP address to connect to the dbANYWHERE Server machine. During development, if you're running the client and dbANYWHERE on the same machine, the client can use "localhost" or "127.0.0.1" to connect to the dbANYWHERE Server machine.

Examples

dbaw://155.64.35.135:8889
dbaw://localhost:8889

Fields

dbaw

Value that defines the protocol and subprotocol for a connection to a dbANYWHERE Server machine. dbaw is the actual value to use.

IP address: Internet Protocol address

dbANYWHERE Server machine's unique IP address via network TCP/IP configuration. The IP address formats are:

•	Local host

The client and dbANYWHERE are on the same machine. We suggest using this configuration during development. Example:

127.0.0.1

•	Numeric

The client and dbANYWHERE are on different machines. Example:

123.45.67.123

•	Alias

The client and dbANYWHERE are on different machines. The client depends on the host or the database server to convert this alias to a numeric IP address. Example:

symantec.com

Port

Unique port number for the dbANYWHERE Server machine’s socket-based service. The port number represents a logical connection that can be called by client machines.


Top of ctask.doc
Top of ctaskprp.doc

This is the top of the ctask.doc file. This file contains procedures for working with components from the Component Library. This file is new to the help project for release 1.01d


Index entries1
Main index entry

Please click on a sub index entry for topic information.


Index entries2
Main index entry

Please click on a sub index entry for topic information.


Adding a dbAWARE field to an existing form

Adding a TextField, that is associated with a database column, to a form is quite simple.

1.	In dbNAVIGATOR , expand the desired server's data source object list.

2.	Expand the appropriate data source's object list by clicking the plus sign.

3.	Expand the object list for the table that contains the desired column.

This picture shows an expanded table object listing.

4. 	Drag the appropriate column item to the Form Designer.

Visual Cafe Pro adds a TextField and Label component to the form. The label component uses the column name as the Text property. If the field is from a table for which supporting dbAWARE components are not yet created, such as a Session component , ConnectionInfo component and a RelationView component, the supporting component is created for you.

5.	Position and size the Text field and label as necessary.


Adding a Grid component

1.	Drag the table icon, from the dbNAVIGATOR window, onto the form.

Visual Cafe Pro then automatically creates all other components that are needed to define the database connection; such as the Session and ConnectionInfo component.

Figure 1, below, is a screen shot of the dbNAVIGATOR window and the Visual Cafe Tutorial's DBA.registation table. The columns display in the Grid, from left to right, in the same order that they appear in dbNAVIAGATOR .

2.	Select the Grid component from the Component Palette and add the Grid to your form.

The Grid is empty. You do not see the actual data until runtime. See Figure 2.

3.	Size the Grid as appropriate.

If query columns do not fit within the Grid component, a scroll slider is provided.

4.	Adjust the column widths by positioning the cursor on the column heading until a double-edge arrow displays. Then, click and drag the column border line left or right.

Note  Column heading text can be customized in code only.

5.	Set the Grid component’s RelationView property to the name of the RelationView component that was created in step 1. The RelationView property is an element of the Binding property

6.	Execute the form (Project [image] Execute.)

Figure 3 shows the sample Grid at runtime. Notice the placement of the Grid buttons. The Grid component uses the database column names as the Grid column headings.

You can narrow the query by adjusting the SELECT clause in the associated RelationView component's Select Clause property.

Figure 1:

Figure 2:

Figure 3:


Adding a Grid component to a form as a detail view

A master/detail relationship can be achieved by adding a Grid component to a form as the detail view.

1.	Select Insert [image] Add Table Wizard.

2.	Complete the wizard using only TextField components.

Help for each wizard page and dialog is available as you run it.

3. 	Specify the join columns by using the component’s Join property.

4.	In the Form Designer, delete all labels and fields that were automatically created for the table.

5.	Drop a Grid component onto the form and size it appropriately.

6.	Define the Grid’s RelationView property.


Entering timestamp data

Timestamp data uses a 24 hour format.

If you enter

1997-02-05 11:00:00.000000000

then the value is interpreted by dbANYWHERE as 11:00am.
If you want the value of 1:00pm, enter

1997--02-05 13:00:00.000000000

Note that nine digits are used in the nanosecond position of the timestamp data, this is due to the java.sql.Timestamp class use of nine digits. Therefore, to enter 123 nanoseconds, you must pad the value with zeros. The value is:

000000123


Changing Grid cell attributes

You may want to change the visual attributes of grid cells such as color, font, and row highlight color. To change these attributes you modify the component’s source code. Place any custom source code after the INIT_CONTROLS code block..

Foreground And Background Colors

The Property List does not provide a property to control the foreground and background colors of Grid cells. You must specify these attributes in code.

Below is a code sample that changes the cell background and foreground colors. The setCellBgColor() and setCellFgColor() methods take as arguments a row number, a column number, and a new color. Note: cell row and cell column numbers are 1-based, not 0-based.

grid1.setCellBgColor(1, 1, Color.blue);
grid1.setCellFgColor(1, 1, Color.white);

You can also change the color of an entire row or column of cells. The method arguments consist of a row (or column) number and a color.

grid1.setColBgColor(1, Color.blue);
grid1.setColFgColor(1, Color.white);
grid1.setRowBgColor(1, Color.red);
grid1.setRowFgColor(1, Color.white);

Fonts

You may want to change the font of a cell or range of cells for emphasis. Below are some examples that illustrate how to change cell, column and row fonts:

grid1.setCelllFont(2, 2, new Font (“Helvetica”, Font.PLAIN, 14));
grid1.setColFont(1, new Font (“TimesRoman”, Font.ITALIC, 18);
grid1.setRowFont(1, new Font (“Courier”, Font.BOLD, 16)

The arguments are the column number (columns are 1-based, not 0-based) and a color as defined in the java.awt.Color class.


Protecting a Grid column

You can protect cells, so that the user cannot modify the data, by enhancing the component's Java code. Like Grid cell colors, you can protect specific cells, a whole row, or a whole column. Place any custom source code after the INIT_CONTROLS code block.

 Below are some examples:

grid1.setCellEditable(1, 1, false);

grid1.setColEditable(2, false);

grid1.setRowEditable(2, false);

In the above syntax, the first argument is the column number and the second argument is Boolean, where "false" equals read-only and "true" equals read-write.


Changing Grid column attributes

You can change attributes of Grid columns, such as heading names, column alignments, heading colors, and heading fonts, by enhancing the Grid component's Java code. Place any custom source code after the INIT_CONTROLS code block.

Changing Column Headings

You can change column headings by adding custom code, as follows:

grid1.setHeading (“Last Name”, 1, 15);
grid1.setHeading (“First Name”, 2, 15);

The third setHeading() argument specifies the width of the column in average character widths.

Changing Column Alignment

You can also modify column alignment. The method arguments are the column number and the alignment type. The alignment can be specified by static final int values attached to the Grid class:

grid1.setColumnAlignment (1, grid1.LEFT);
grid1.setColumnAlignment (2, grid1.CENTER);
grid1.setColumnAlignment (3, grid1.RIGHT);

Changing Column Heading Colors And Font

You can modify column heading and font attributes. The setHeadingColor() method changes the foreground and background colors of a column heading.  The setHeadingFont() method changes the font of a column heading:

grid1.setHeadingColors (1, Color.black, Color.white);
grid1.setHeadingFont (new Font(“TimesRoman”, Font.BOLD, 18), 1);


Defining automatic Grid row numbering

Automatic row numbering can be turned on or off.  When activated, the starting row number can be set by using the setupAutonumbering() method, for example,

grid1.setupAutonumbering (1);  // begins auto-row numbering at 1

grid1.setupAutonumbering (5);  // begins auto-row numbering at 4

grid1.setupAutonumbering (0);  // turns off auto-row numbering

Place any custom source code after the INIT_CONTROLS code block.


Defining automatic Grid redraw

Each time a grid component is updated, it is automatically redrawn.  If you are going to make several changes to your grid (column headings, cell color changes, etc.,) it is a good idea to turn off the automatic redraw capability. Once you have made all your changes, you can turn it back on again:

grid1.setAutoRedraw (false);  // turns off auto-redraw

// make changes to the grid here

grid1.setAutoRedraw (true);   // turns on auto-redraw

Place any custom source code after the INIT_CONTROLS code block.


Modifying the Grid toolbar

You can add additional functionality to a Grid toolbar by

•	creating a customized Grid event handler with the added functionality

•	then, informing the Grid about the new event handler

Each grid component has a DefaultTvEventHandler object that provides the standard functionality of the Grid: Insert, Go To, Undo, Restart, Delete, Undelete, and Save. Additional functions are made through a custom EventHandler object that extends from the DefaultTvEventHandler.

Place any custom source code after the INIT_CONTROLS code block.

Adding Search Capability

The following example adds a few components to the toolbar and implements a standard search capability within a column. New features include a search field, a forward and backward search direction radio button, and a Go button (to start the search).

1.	Create a basic project with a Grid.

2.	When the Grid is functional and displays data, add import statements at the top of the Grid source code:

import symantec.itools.db.awt.Grid;
import symantec.itools.db.awt.Coordinate;
import symantec.itools.db.awt.DataNotAvailable;
import symantec.itools.db.awt.DefaultTvEventHandler;

These import statements provide the necessary classes to create the custom event handler.

3.	Add the following code for a custom event handler. Code notes follow the code sample.

 1: class MyEventHandler extends DefaultTvEventHandler {

 2:     TextField tfSearch;

 3:     Checkbox  cbNext, cbPrev;

 4:     Button    btnGo;

 5:     Grid      grid;

 6:

 7:    public void setupView (Grid gr) {

 8:        super.setupView(gr);

 9:        grid = gr;

10:

11:        gr.addToToolbar (tfSearch = new TextField(15));

12:        CheckboxGroup cbg = new CheckboxGroup();

13:        gr.addToToolbar (cbNext = new Checkbox("Next", cbg, true));

14:        gr.addToToolbar (cbPrev = new Checkbox("Prev", cbg, false));

15:        gr.addToToolbar (btnGo = new Button("Search"));

16:    }

17:

18:    public boolean handleToolbarEvent (Event e) {

19:        if (e.target == tfSearch && e.id == e.ACTION_EVENT) {

20:            findSubstring(tfSearch.getText(), 1, cbNext.getState());

21:            return true;

22:        } else if (e.target == btnGo && e.id == e.ACTION_EVENT) {

23:            findSubstring(tfSearch.getText(), 1, cbNext.getState());

24:            return true;

25:        }

26:        return super.handleToolbarEvent(e);

27:    }

28:

29:    void findSubstring(String query, int col, boolean forward) {

30:        if (col < 0 || col >= grid.getNumberOfCols()) {

31:            throw new IllegalArgumentException ("col="+(col+1)+" is not

32:              in view");

33:        }

34:        int start, stop = grid.getNumberOfVisibleRows() - 1;

35:        query = query.toUpperCase();

36:

37:        int step = forward ? 1 : -1;

38:        Coordinate curr = grid.getCurrentCellCoordinates();

39:        if (curr != null) {

40:            start = curr.row() + step;

41:        } else if (forward) {

42:            start = 0;

43:        } else {

44:            start = grid.getNumberOfVisibleRows() - 1;

45:            stop = 0;

46:        }

47:        int stringAt = -1;

48:        try {

49:            int index = -1;

50:            for (int row=start; row <=stop; row +=step) {

51:                String currText = grid.getCellText(row+1,

52:                  col+1).toUpperCase();

53:                index = currText.indexOf(query);

54:

55:                if (index != -1) {

56:                    stringAt = row + 1;

57:                }

58:            }

59:        } catch (DataNotAvailable ex) {

60:            ex.printStackTrace();

61:        }

62:

63:        if (stringAt != -1) {

64:            grid.setCurrentCell (stringAt, 2);

65:        } else {

66:            System.out.println("Did not find "+query);

67:        }

68:    }

69: }

Code Notes

Lines 11 through 15 add the new components to the toolbar.

Lines 18 through 27 act as the new handleEvent() method for the Grid.  While most of the standard grid events are dealt with internally, the handleEvent() method deals with a Return key action even from the Search TextField or a press of the Search Go button. In both cases, the findSubString() method is being called on to perform the search.

Lines 29 through 68 make up the findSubString() method. The arguments to findSubString() are:

•	the text to search for

•	the column to search within

•	the direction to search (forward or backward)

This method searches through the specified column to find a cell containing a string that matches the search string (after conversion to uppercase).

Lines 30 through 33 assure that the column to search is within the range of actual columns in the grid. If the column to search is not within the actual columns within the grid, the IllegalArgumentException is thrown.

Line 34 declares the start and stop position variables for the search based on the number of rows available to search.

Line 35 converts the query to uppercase for the search.

Line 37 determines the step for the search depending on the direction of the search. If the search is a forward search, the step is set to positive value of 1. If the search is a backwards search, the step is set to a value of negative 1.

Lines 38 through 46 determine the starting and stopping point of the search.

Lines 47 through 61 start to check each cell in the given column to see if the cell contains a match to the search string. If not, the next cell is selected and searched, and so on, until the search is successful or the search range has been exhausted.

Lines 62 through 67 either send a message to the console saying the search was unsuccessful, or select the cell that contained the match.

Plugging in the new capability

Once you have constructed the new MyEventHandler object, you must connect it to the existing Grid object. Use the installEventHandler() method with an instance of the MyEventHandler object as a parameter, as shown below.

 1:	. . .

 2:	try {

 3:	grid1 = new symantec.itools.db.awt.Grid(DBA_employee);

 4:	grid1.addUndoButton();

 5:	grid1.addDeleteButton();

 6:	grid1.addUndeleteButton();

 7:	} catch (symjava.sql.SQLException e) {

 8:	    System.out.println(e.getMessage());

 9:	    return;

10:	}

11:	grid1.reshape(24,12,528,327);

12:	keyPressManagerPanel1.add(grid1);

13:	//}}

14:        grid1.installEventHandler(new MyEventHandler());

15:	}

Code Notes

After adding the Grid to a project, lines 1 through 13 and 15 already exist. Line 14 was added to install the new MyEventHandler object to the grid component.

The line on which the installEventHandler() method is placed is important. Notice that it is just below the line with the //}} tag. This tag declares the end of an area of code that is automatically maintained by Visual Café Pro.

Any manual code placed inside the matching //{{ and //}} tags may be removed by Visual Café Pro’s two-way development system when Visual Cafe Pro does code maintenance. Placing the installEventHandler() method outside the tags ensures that Visual Café Pro does not remove or change your code.


Using more than one Data Source

It is common in medium- and large-scale database projects to use data from more than one database and/or from more than one server.

Additional Session components

You need an additional Session component if you add another database that is served by a different dbANYWHERE workgroup server. Multiple workgroup servers can be accessed across multiple dbANYWHERE Server machines.

Additional ConnectionInfo components

You need an additional ConnectionInfo component if you are adding another database that is served by the same workgroup server.

To add another ConnectionInfo component, open the dbNAVIGATOR window and drag the new data source to your Project window.

Additional RelationView component

You need an additional RelationView component if you are adding another table from the same database and the same workgroup server.

To add another RelationView component, open the dbNAVIGATOR window and drag the new data table to your Project Objects window.


Creating custom database logons

You may want to provide a database logon screen that allows users to enter their own username and password. Using a logon dialog allows you to control and/or limit user access.  Overview information is available in How the logon process works later in this topic.

Visual Cafe Pro provides a basic logon dialog, but you may wish to create your own custom logon.  A custom logon can provide different components and give you more control over the details of the logon process such as which database to connect with.  It also gives you more control over the look-and-feel of the logon process.

Tip  Another way to implement your own logon dialog is to use the PasswordDialog component, which is a simple frame that asks for a username and password. Use the PasswordDialog to obtain the username and password, and pass those values to the ConnectionInfo component by using the setUser() and setPassword() methods shown on lines 12 and 13 of the “how the logon process works” code segment below. Creating a custom logon can get complicated when you want to handle invalid user input. In that case, you can create a sophisticated logon dialog by using the Logon interface as described below.

A custom logon class must implement the Logon interface. The Logon interface is defined in Logon.java located in the symantec.itools.db.pro package.

To understand how to create a custom logon, review the default LogonFrame source code.  To review the source code, follow these steps:

1.	Open or create a database project.

   Details on this step

2.	Open the Class Browser window (Window [image] Class Browser or CTRL+SHIFT+C)

3.	Open the symantec.itools.db.awt package (at the bottom of the list)

4	Right-click on the LogonFrame and select Go to Source.

The fastest way to create your own custom logon is to copy the displayed source code into a new file and make your changes from there.

5.	Select File [image] New File and enter the following code:

1: public class MyLogonFrame extends symantec.itools.db.awt.LogonFrame

2: {

3:     public MyLogonFrame() {

4: 	setBackground(java.awt.Color.lightGray);

5:     }

6: }

This code produces the same logon box as the PasswordDialog component, but has a light gray background color instead of the default white.

6.	The Session object will call the installed Logon object’s logonFailed method whenever dbANYWHERE fails to connect to a database.

Logon.logonFailed returns a boolean indicating whether dbANYWHERE should continue to try to connect to the database.

The default behavior for symantec.itools.db.awt.LogonFrame.logonFailed method is to display a Frame that prompts the user for a new name and password. If the user clicks the OK button, LogonFrame will set the ConnectionInfo's username and password to the new values and return the boolean true so dbANYWHERE will attempt to connect again. If the user clicks Cancel, a boolean false is returned. dbANYWHERE will, in this case, throw a SQLConnectionException back to the method that initiated the database connection. LogonFrame ignores the retries parameter.

You may want to modify LogonFrame's logonFailed implementation. For instance:

•	You may want to limit the number of attempts that the user has to connect to a database.

•	You may want to validate the username and password that was typed in.

You will have to implement the logonFailed method in your MyLogonFrame class:

public boolean logonFailed(ConnectionInfo conn, int retries)
{
     //Examine the retries parameter and return false if it is

     //greater than some predefine value
     if (retries > 5)
         return false;

     //Call LogonFrame's implementation
     boolean continue = super.logonFailed(conn,retries);

     //If user wants to continue, you may want to validate the new
     //username and password
     if (continue)
     {
        String username = conn.getUser();
        String password = conn.getPassword();

        //Validate username and password
        //return true if validation passed or false if it failed
      }

      return continue ;
}

7.	Save the file as MyLogonFrame.java. Be sure to check the Add to Project checkbox in the lower left corner of the Save As dialog box.

8.	In your main applet, the project needs to use your new logon frame. Go to the line that instantiates the logon frame (line 4 in the previous code example) and change the reference of symantec.itools.db.awt.LogonFrame to MyLogonFrame.

9.	In order for the logon frame to appear at all, you must comment out and remove the user name and password.  Lines 12 and 13 of the code snippet below show where those items are.  Remove them from the property lists as well (they are properties of the ConnectionInfo component).  You must remove both sources independently, since Visual Café Pro does not currently support two-way development on the ConnectionInfo component.

10.	Execute your project.

How The Logon Process Works

The following code segment illustrates the relatively simple steps involved in the logon process. The dialog for this logon follows the code. Code notes follow the illustration.

 1  try {

 2      symantec = new

 3          symantec.itools.db.pro.Session("dbaw://localhost:8889");

 4      symantecLogonFrame = new symantec.itools.db.awt.LogonFrame();

 5      symantec.setLogonObject(symantecLogonFrame);

 6  } catch (symjava.sql.SQLException e) {

 7      System.out.println(e.getMessage());

 8      return;

 9  }

10  SQL_Anywhere_5_0_Sample = new

11      symantec.itools.db.pro.ConnectionInfo("SQL Anywhere 5.0 Sample");

12  SQL_Anywhere_5_0_Sample.setUser("dba");

13  SQL_Anywhere_5_0_Sample.setPassword("sql");

14  SQL_Anywhere_5_0_Sample.setAutoDisconnect(false);

15  try {

16      symantec.itools.db.pro.Request DBA_packagesRequest = new

17         symantec.itools.db.pro.Request(symantec,SQL_Anywhere_5_0_Sample);

18      . . .

19  } catch (symjava.sql.SQLException e) {

20      System.out.println(e.getMessage());

21      return;

22  }

Code Notes

On line 4, a LogonFrame object is instantiated.  The LogonFrame displays whenever dbANYWHERE fails to connect to a database. This may occur because

•	the ConnectionInfo object has an empty or invalid username or password.

•	the username or password typed in the User Authentication Frame previously by the enduser was invalid.

On line 5, the LogonFrame is associated with the Session component, which means that only one type of logon object is associated with a given dbANYWHERE Session.

Lines 10 through 14 instantiate and populate the ConnectionInfo component.  In particular, note lines 12 and 13 that set the username and password for the ConnectionInfo component.

Lines 16 and 17 (all one line, broken into two) is where the first access to the database occurs.  The parameters for the Request object are the Session and ConnectionInfo components.

If lines 12 and 13 were commented out, the LogonFrame object would automatically appear to ask for a username and password.  These two fields are then be passed back to the logon process of the Request object shown in step 4.